<head>
<title>Manual Page</title>
</head>
<body>
<pre>
</pre><h2>NAME</h2><pre>
     gl_get_line,            new_GetLine,            del_GetLine,
     gl_customize_completion,                 gl_change_terminal,
     gl_configure_getline,   gl_load_history,    gl_save_history,
     gl_group_history,        gl_show_history,       gl_watch_fd,
     gl_terminal_size,    gl_resize_history,    gl_limit_history,
     gl_clear_history,    gl_toggle_history,   gl_lookup_history,
     gl_state_of_history,                    gl_range_of_history,
     gl_size_of_history,     gl_echo_mode,     gl_replace_prompt,
     gl_prompt_style,      gl_ignore_signal,      gl_trap_signal,
     gl_last_signal - allow the user to compose an input line

</pre><h2>SYNOPSIS</h2><pre>
     #include &lt;stdio.h&gt;
     #include &lt;libtecla.h&gt;

     GetLine *new_GetLine(size_t linelen, size_t histlen);

     GetLine *del_GetLine(GetLine *gl);

     char *gl_get_line(GetLine *gl, const char *prompt,
                      const char *start_line, int start_pos);

     int gl_customize_completion(GetLine *gl, void *data,
                                 CplMatchFn *match_fn);

     int gl_change_terminal(GetLine *gl, FILE *input_fp,
                            FILE *output_fp, const char *term);

     int gl_configure_getline(GetLine *gl,
                              const char *app_string,
                              const char *app_file,
                              const char *user_file);

     int gl_save_history(GetLine *gl, const char *filename,
                         const char *comment, int max_lines);

     int gl_load_history(GetLine *gl, const char *filename,
                         const char *comment);

     int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
                     GlFdEventFn *callback, void *data);

     int gl_group_history(GetLine *gl, unsigned stream);

     int gl_show_history(GetLine *gl, FILE *fp,
                         const char *fmt, int all_groups,
                         int max_lines);

     int gl_resize_history(GetLine *gl, size_t bufsize);

     void gl_limit_history(GetLine *gl, int max_lines);
     void gl_clear_history(GetLine *gl, int all_groups);

     void gl_toggle_history(GetLine *gl, int enable);

     GlTerminalSize gl_terminal_size(GetLine *gl,
                                     int def_ncolumn,
                                     int def_nline);

     int gl_lookup_history(GetLine *gl, unsigned long id,
                           GlHistoryLine *hline);

     void gl_state_of_history(GetLine *gl,
                              GlHistoryState *state);

     void gl_range_of_history(GetLine *gl,
                              GlHistoryRange *range);

     void gl_size_of_history(GetLine *gl, GlHistorySize *size);

     void gl_echo_mode(GetLine *gl, int enable);

     void gl_replace_prompt(GetLine *gl, const char *prompt);

     void gl_prompt_style(GetLine *gl, GlPromptStyle style);

     int gl_ignore_signal(GetLine *gl, int signo);

     int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
                        GlAfterSignal after, int errno_value);

     int gl_last_signal(const GetLine *gl);



</pre><h2>DESCRIPTION</h2><pre>
     The gl_get_line() function is part of the tecla library (see
     the <a href="libtecla.html">libtecla(3)</a> man page). If the user is typing at a termi-
     nal, it prompts them for an line  of  input,  then  provides
     interactive editing facilities, similar to those of the unix
     tcsh shell. In addition to simple command-line  editing,  it
     supports  recall  of  previously  entered command lines, TAB
     completion of file names, and in-line wild-card expansion of
     filenames.


</pre><h2>AN EXAMPLE</h2><pre>
     The following shows a complete example of  how  to  use  the
     gl_get_line() function to get input from the user:

       #include &lt;stdio.h&gt;
       #include &lt;locale.h&gt;
       #include &lt;libtecla.h&gt;
       int main(int argc, char *argv[])
       {
         char *line;    /* The line that the user typed */
         GetLine *gl;   /* The gl_get_line() resource object */

         setlocale(LC_CTYPE, ""); /* Adopt the user's choice */
                                  /* of character set. */

         gl = new_GetLine(1024, 2048);
         if(!gl)
           return 1;

         while((line=gl_get_line(gl, "$ ", NULL, -1)) != NULL &amp;&amp;
                strcmp(line, "exit\n") != 0)
           printf("You typed: %s\n", line);

         gl = del_GetLine(gl);
         return 0;
       }

     In  the  example,  first  the  resources   needed   by   the
     gl_get_line() function are created by calling new_GetLine().
     This allocates the memory used in subsequent  calls  to  the
     gl_get_line()  function,  including  the  history buffer for
     recording previously entered lines. Then one or  more  lines
     are read from the user, until either an error occurs, or the
     user types exit. Then finally the resources that were  allo-
     cated  by  new_GetLine(), are returned to the system by cal-
     ling del_GetLine(). Note the use of the NULL return value of
     del_GetLine()  to make gl NULL. This is a safety precaution.
     If  the  program  subsequently  attempts  to  pass   gl   to
     gl_get_line(),  said  function  will complain, and return an
     error, instead of attempting to  use  the  deleted  resource
     object.



</pre><h2>THE FUNCTIONS USED IN THE EXAMPLE</h2><pre>
     The descriptions of the functions used in the example are as
     follows:

       GetLine *new_GetLine(size_t linelen, size_t histlen)

     This  function   creates   the   resources   used   by   the
     gl_get_line()  function and returns an opaque pointer to the
     object that contains them.  The maximum length of  an  input
     line  is  specified via the linelen argument, and the number
     of bytes to allocate for storing history lines is set by the
     histlen argument. History lines are stored back-to-back in a
     single buffer of this size. Note that this  means  that  the
     number  of  history  lines  that  can be stored at any given
     time, depends on the lengths of the  individual  lines.   If
     you want to place an upper limit on the number of lines that
     can be stored, see the gl_limit_history() function described
     later.  If you don't want history at all, specify histlen as
     zero, and no history buffer will be allocated.

     On error, a  message  is  printed  to  stderr  and  NULL  is
     returned.

       GetLine *del_GetLine(GetLine *gl)

     This function deletes the resources that were returned by  a
     previous call to new_GetLine(). It always returns NULL (ie a
     deleted object). It does nothing if the gl argument is NULL.

       char *gl_get_line(GetLine *gl, const char *prompt,
                        const char *start_line, int start_pos);

     The gl_get_line() function can be called any number of times
     to  read input from the user. The gl argument must have been
     previously returned by a call to new_GetLine().  The  prompt
     argument  should be a normal NUL terminated string, specify-
     ing the prompt to present the user with. By default  prompts
     are   displayed   literally,   but   if   enabled  with  the
     gl_prompt_style() function (see later), prompts can  contain
     directives to do underlining, switch to and from bold fonts,
     or turn highlighting on and off.

     If you want to specify the initial contents of the line, for
     the user to edit, pass the desired string via the start_line
     argument. You can then specify which character of this  line
     the cursor is initially positioned over, using the start_pos
     argument. This should be -1 if you want the cursor to follow
     the  last  character of the start line. If you don't want to
     preload the line in this manner, send  start_line  as  NULL,
     and set start_pos to -1.

     The gl_get_line() function returns a  pointer  to  the  line
     entered  by  the user, or NULL on error or at the end of the
     input. The returned pointer is  part  of  the  specified  gl
     resource  object,  and  thus  should  not  be  free'd by the
     caller, or assumed to be unchanging from  one  call  to  the
     next.  When  reading  from  a user at a terminal, there will
     always be a newline character at the  end  of  the  returned
     line.   When  standard input is being taken from a pipe or a
     file, there will similarly be a  newline  unless  the  input
     line  was  too  long to store in the internal buffer. In the
     latter case you should call gl_get_line() again to read  the
     rest   of   the   line.   Note   that  this  behavior  makes
     gl_get_line() similar to fgets().  In fact when stdin  isn't
     connected to a terminal,gl_get_line() just calls fgets().


</pre><h2>OPTIONAL PROMPT FORMATTING</h2><pre>
     Whereas by default the prompt string  that  you  specify  is
     displayed  literally,  without any special interpretation of
     the characters within it, the gl_prompt_style() function can
     be  used to enable optional formatting directives within the
     prompt.

       void gl_prompt_style(GetLine *gl, GlPromptStyle style);

     The style argument, which specifies  the  formatting  style,
     can take any of the following values:

       GL_FORMAT_PROMPT   -  In this style, the formatting
                             directives described below, when
                             included in prompt strings, are
                             interpreted as follows:

                               %B  -  Display subsequent
                                      characters with a bold
                                      font.
                               %b  -  Stop displaying characters
                                      with the bold font.
                               %F  -  Make subsequent characters
                                      flash.
                               %f  -  Turn off flashing
                                      characters.
                               %U  -  Underline subsequent
                                      characters.
                               %u  -  Stop underlining
                                      characters.
                               %P  -  Switch to a pale (half
                                      brightness) font.
                               %p  -  Stop using the pale font.
                               %S  -  Highlight subsequent
                                      characters (also known as
                                      standout mode).
                               %s  -  Stop highlighting
                                      characters.
                               %V  -  Turn on reverse video.
                               %v  -  Turn off reverse video.
                               %%  -  Display a single %
                                      character.

                             For example, in this mode, a prompt
                             string like "%UOK%u$ " would
                             display the prompt "OK$ ",
                             but with the OK part
                             underlined.

                             Note that although a pair of
                             characters that starts with a %
                             character, but doesn't match any of
                             the above directives is displayed
                             literally, if a new directive is
                             subsequently introduced which does
                             match, the displayed prompt will
                             change, so it is better to always
                             use %% to display a literal %.

                             Also note that not all terminals
                             support all of these text
                             attributes, and that some substitute
                             a different attribute for missing
                             ones.

       GL_LITERAL_PROMPT  -  In this style, the prompt string is
                             printed literally. This is the
                             default style.



</pre><h2>THE AVAILABLE KEY BINDING FUNCTIONS</h2><pre>
     The gl_get_line() function provides a  number  of  functions
     which  can  be  bound  to  key sequences. The names of these
     functions, and what they do, are given below.

       user-interrupt           -  Send a SIGINT signal to the
                                   parent process.
       abort                    -  Send a SIGABRT signal to the
                                   parent process.
       suspend                  -  Suspend the parent process.
       stop-output              -  Pause terminal output.
       start-output             -  Resume paused terminal output.
       literal-next             -  Arrange for the next character
                                   to be treated as a normal
                                   character. This allows control
                                   characters to be entered.
       cursor-right             -  Move the cursor one character
                                   right.
       cursor-left              -  Move the cursor one character
                                   left.
       insert-mode              -  Toggle between insert mode and
                                   overwrite mode.
       beginning-of-line        -  Move the cursor to the
                                   beginning of the line.
       end-of-line              -  Move the cursor to the end of
                                   the line.
       delete-line              -  Delete the contents of the
                                   current line.
       kill-line                -  Delete everything that follows
                                   the cursor.
       backward-kill-line       -  Delete all characters between
                                   the cursor and the start of the
                                   line.
       forward-word             -  Move to the end of the word
                                   which follows the cursor.
       forward-to-word          -  Move the cursor to the start of
                                   the word that follows the
                                   cursor.
       backward-word            -  Move to the start of the word
                                   which precedes the cursor.
       goto-column              -  Move the cursor to the
                                   1-relative column in the line
                                   specified by any preceding
                                   digit-argument sequences (see
                                   ENTERING REPEAT COUNTS below).
       find-parenthesis         -  If the cursor is currently
                                   over a parenthesis character,
                                   move it to the matching
                                   parenthesis character. If not
                                   over a parenthesis character
                                   move right to the next close
                                   parenthesis.
       forward-delete-char      -  Delete the character under the
                                   cursor.
       backward-delete-char     -  Delete the character which
                                   precedes the cursor.
       list-or-eof              -  This is intended for binding
                                   to ^D. When invoked when the
                                   cursor is within the line it
                                   displays all possible
                                   completions then redisplays
                                   the line unchanged. When
                                   invoked on an empty line, it
                                   signals end-of-input (EOF) to
                                   the caller of gl_get_line().
       del-char-or-list-or-eof  -  This is intended for binding
                                   to ^D. When invoked when the
                                   cursor is within the line it
                                   invokes forward-delete-char.
                                   When invoked at the end of the
                                   line it displays all possible
                                   completions then redisplays
                                   the line unchanged. When
                                   invoked on an empty line, it
                                   signals end-of-input (EOF) to
                                   the caller of gl_get_line().
       forward-delete-word      -  Delete the word which follows
                                   the cursor.
       backward-delete-word     -  Delete the word which precedes
                                   the cursor.
       upcase-word              -  Convert all of the characters
                                   of the word which follows the
                                   cursor, to upper case.
       downcase-word            -  Convert all of the characters
                                   of the word which follows the
                                   cursor, to lower case.
       capitalize-word          -  Capitalize the word which
                                   follows the cursor.
       change-case              -  If the next character is upper
                                   case, toggle it to lower case
                                   and vice versa.
       redisplay                -  Redisplay the line.
       clear-screen             -  Clear the terminal, then
                                   redisplay the current line.
       transpose-chars          -  Swap the character under the
                                   cursor with the character just
                                   before the cursor.
       set-mark                 -  Set a mark at the position of
                                   the cursor.
       exchange-point-and-mark  -  Move the cursor to the last
                                   mark that was set, and move
                                   the mark to where the cursor
                                   used to be.
       kill-region              -  Delete the characters that lie
                                   between the last mark that was
                                   set, and the cursor.
       copy-region-as-kill      -  Copy the text between the mark
                                   and the cursor to the cut
                                   buffer, without deleting the
                                   original text.
       yank                     -  Insert the text that was last
                                   deleted, just before the
                                   current position of the cursor.
       append-yank              -  Paste the current contents of
                                   the cut buffer, after the
                                   cursor.
       up-history               -  Recall the next oldest line
                                   that was entered. Note that
                                   in vi mode you are left in
                                   command mode.
       down-history             -  Recall the next most recent
                                   line that was entered. If no
                                   history recall session is
                                   currently active, the next
                                   line from a previous recall
                                   session is recalled. Note that
                                   in vi mode you are left in
                                   command mode.
       history-search-backward  -  Recall the next oldest line
                                   who's prefix matches the string
                                   which currently precedes the
                                   cursor (in vi command-mode the
                                   character under the cursor is
                                   also included in the search
                                   string).  Note that in vi mode
                                   you are left in command mode.
       history-search-forward   -  Recall the next newest line
                                   who's prefix matches the string
                                   which currently precedes the
                                   cursor (in vi command-mode the
                                   character under the cursor is
                                   also included in the search
                                   string).  Note that in vi mode
                                   you are left in command mode.
       history-re-search-backward -Recall the next oldest line
                                   who's prefix matches that
                                   established by the last
                                   invocation of either
                                   history-search-forward or
                                   history-search-backward.
       history-re-search-forward - Recall the next newest line
                                   who's prefix matches that
                                   established by the last
                                   invocation of either
                                   history-search-forward or
                                   history-search-backward.
       complete-word            -  Attempt to complete the
                                   incomplete word which
                                   precedes the cursor. Unless
                                   the host program has customized
                                   word completion, filename
                                   completion is attempted. In vi
                                   commmand mode the character
                                   under the cursor is also
                                   included in the word being
                                   completed, and you are left in
                                   vi insert mode.
       expand-filename          -  Within the command line, expand
                                   wild cards, tilde expressions
                                   and dollar expressions in the
                                   filename which immediately
                                   precedes the cursor. In vi
                                   commmand mode the character
                                   under the cursor is also
                                   included in the filename being
                                   expanded, and you are left in
                                   vi insert mode.
       list-glob                -  List any filenames which match
                                   the wild-card, tilde and dollar
                                   expressions in the filename
                                   which immediately precedes the
                                   cursor, then redraw the input
                                   line unchanged.
       list-history             -  Display the contents of the
                                   history list for the current
                                   history group. If a repeat
                                   count of &gt; 1 is specified,
                                   only that many of the most
                                   recent lines are displayed.
                                   See the "ENTERING REPEAT
                                   COUNTS" section.
       read-from-file           -  Temporarily switch to reading
                                   input from the file who's
                                   name precedes the cursor.
       read-init-files          -  Re-read teclarc configuration
                                   files.
       beginning-of-history     -  Move to the oldest line in the
                                   history list. Note that in vi
                                   mode you are left in command
                                   mode.
       end-of-history           -  Move to the newest line in the
                                   history list (ie. the current
                                   line). Note that in vi mode
                                   this leaves you in command
                                   mode.
       digit-argument           -  Enter a repeat count for the
                                   next key-binding function.
                                   For details, see the ENTERING
                                   REPEAT COUNTS section.
       newline                  -  Terminate and return the
                                   current contents of the
                                   line, after appending a
                                   newline character. The newline
                                   character is normally '\n',
                                   but will be the first
                                   character of the key-sequence
                                   that invoked the newline
                                   action, if this happens to be
                                   a printable character. If the
                                   action was invoked by the
                                   '\n' newline character or the
                                   '\r' carriage return
                                   character, the line is
                                   appended to the history
                                   buffer.
       repeat-history           -  Return the line that is being
                                   edited, then arrange for the
                                   next most recent entry in the
                                   history buffer to be recalled
                                   when gl_get_line() is
                                   next called. Repeatedly
                                   invoking this action causes
                                   successive historical input
                                   lines to be re-executed. Note
                                   that this action is equivalent
                                   to the 'Operate' action in
                                   ksh.
       ring-bell                -  Ring the terminal bell, unless
                                   the bell has been silenced via
                                   the nobeep configuration
                                   option (see the THE TECLA
                                   CONFIGURATION FILE section).
       forward-copy-char        -  Copy the next character into
                                   the cut buffer (NB. use repeat
                                   counts to copy more than one).
       backward-copy-char       -  Copy the previous character
                                   into the cut buffer.
       forward-copy-word        -  Copy the next word into the cut
                                   buffer.
       backward-copy-word       -  Copy the previous word into the
                                   cut buffer.
       forward-find-char        -  Move the cursor to the next
                                   occurrence of the next
                                   character that you type.
       backward-find-char       -  Move the cursor to the last
                                   occurrence of the next
                                   character that you type.
       forward-to-char          -  Move the cursor to the
                                   character just before the next
                                   occurrence of the next
                                   character that the user types.
       backward-to-char         -  Move the cursor to the
                                   character just after the last
                                   occurrence before the cursor
                                   of the next character that the
                                   user types.
       repeat-find-char         -  Repeat the last
                                   backward-find-char,
                                   forward-find-char,
                                   backward-to-char or
                                   forward-to-char.
       invert-refind-char       -  Repeat the last
                                   backward-find-char,
                                   forward-find-char,
                                   backward-to-char, or
                                   forward-to-char in the
                                   opposite direction.
       delete-to-column         -  Delete the characters from the
                                   cursor up to the column that
                                   is specified by the repeat
                                   count.
       delete-to-parenthesis    -  Delete the characters from the
                                   cursor up to and including
                                   the matching parenthesis, or
                                   next close parenthesis.
       forward-delete-find      -  Delete the characters from the
                                   cursor up to and including the
                                   following occurence of the
                                   next character typed.
       backward-delete-find     -  Delete the characters from the
                                   cursor up to and including the
                                   preceding occurence of the
                                   next character typed.
       forward-delete-to        -  Delete the characters from the
                                   cursor up to, but not
                                   including, the following
                                   occurence of the next
                                   character typed.
       backward-delete-to       -  Delete the characters from the
                                   cursor up to, but not
                                   including, the preceding
                                   occurence of the next
                                   character typed.
       delete-refind            -  Repeat the last *-delete-find
                                   or *-delete-to action.
       delete-invert-refind     -  Repeat the last *-delete-find
                                   or *-delete-to action, in the
                                   opposite direction.
       copy-to-column           -  Copy the characters from the
                                   cursor up to the column that
                                   is specified by the repeat
                                   count, into the cut buffer.
       copy-to-parenthesis      -  Copy the characters from the
                                   cursor up to and including
                                   the matching parenthesis, or
                                   next close parenthesis, into
                                   the cut buffer.
       forward-copy-find        -  Copy the characters from the
                                   cursor up to and including the
                                   following occurence of the
                                   next character typed, into the
                                   cut buffer.
       backward-copy-find       -  Copy the characters from the
                                   cursor up to and including the
                                   preceding occurence of the
                                   next character typed, into the
                                   cut buffer.
       forward-copy-to          -  Copy the characters from the
                                   cursor up to, but not
                                   including, the following
                                   occurence of the next
                                   character typed, into the cut
                                   buffer.
       backward-copy-to         -  Copy the characters from the
                                   cursor up to, but not
                                   including, the preceding
                                   occurence of the next
                                   character typed, into the cut
                                   buffer.
       copy-refind              -  Repeat the last *-copy-find
                                   or *-copy-to action.
       copy-invert-refind       -  Repeat the last *-copy-find
                                   or *-copy-to action, in the
                                   opposite direction.
       vi-mode                  -  Switch to vi mode from emacs
                                   mode.
       emacs-mode               -  Switch to emacs mode from vi
                                   mode.
       vi-insert                -  From vi command mode, switch to
                                   insert mode.
       vi-overwrite             -  From vi command mode, switch to
                                   overwrite mode.
       vi-insert-at-bol         -  From vi command mode, move the
                                   cursor to the start of the line
                                   and switch to insert mode.
       vi-append-at-eol         -  From vi command mode, move the
                                   cursor to the end of the line
                                   and switch to append mode.
       vi-append                -  From vi command mode, move the
                                   cursor one position right, and
                                   switch to insert mode.
       vi-replace-char          -  From vi command mode, replace
                                   the character under the cursor
                                   with the the next character
                                   entered.
       vi-forward-change-char   -  From vi command mode, delete
                                   the next character then enter
                                   insert mode.
       vi-backward-change-char  -  From vi command mode, delete
                                   the preceding character then
                                   enter insert mode.
       vi-forward-change-word   -  From vi command mode, delete
                                   the next word then enter
                                   insert mode.
       vi-backward-change-word  -  From vi command mode, delete
                                   the preceding word then
                                   enter insert mode.
       vi-change-rest-of-line   -  From vi command mode, delete
                                   from the cursor to the end of
                                   the line, then enter insert
                                   mode.
       vi-change-line           -  From vi command mode, delete
                                   the current line, then enter
                                   insert mode.
       vi-change-to-bol         -  From vi command mode, delete
                                   all characters between the
                                   cursor and the beginning of
                                   the line, then enter insert
                                   mode.
       vi-change-to-column      -  From vi command mode, delete
                                   the characters from the cursor
                                   up to the column that is
                                   specified by the repeat count,
                                   then enter insert mode.
       vi-change-to-parenthesis -  Delete the characters from the
                                   cursor up to and including
                                   the matching parenthesis, or
                                   next close parenthesis, then
                                   enter vi insert mode.
       vi-forward-change-find   -  From vi command mode, delete
                                   the characters from the
                                   cursor up to and including the
                                   following occurence of the
                                   next character typed, then
                                   enter insert mode.
       vi-backward-change-find  -  From vi command mode, delete
                                   the characters from the
                                   cursor up to and including the
                                   preceding occurence of the
                                   next character typed, then
                                   enter insert mode.
       vi-forward-change-to     -  From vi command mode, delete
                                   the characters from the
                                   cursor up to, but not
                                   including, the following
                                   occurence of the next
                                   character typed, then enter
                                   insert mode.
       vi-backward-change-to    -  From vi command mode, delete
                                   the characters from the
                                   cursor up to, but not
                                   including, the preceding
                                   occurence of the next
                                   character typed, then enter
                                   insert mode.
       vi-change-refind         -  Repeat the last
                                   vi-*-change-find or
                                   vi-*-change-to action.
       vi-change-invert-refind  -  Repeat the last
                                   vi-*-change-find or
                                   vi-*-change-to action, in the
                                   opposite direction.
       vi-undo                  -  In vi mode, undo the last
                                   editing operation.
       vi-repeat-change         -  In vi command mode, repeat the
                                   last command that modified the
                                   line.


</pre><h2>DEFAULT KEY BINDINGS IN EMACS MODE</h2><pre>
     The following default key bindings, which can  be  overriden
     by  the tecla configuration file, are designed to mimic most
     of the bindings of the unix tcsh shell, when it is in  emacs
     editing mode.

     This is the default editing mode of the tecla library.

     Note that a key sequence like  ^A  or  C-a  means  hold  the
     control-key down while pressing the letter A, and that where
     you see \E or M- in a binding, this  represents  the  escape
     key   or   the   Meta   modifier  key.  Also  note  that  to
     gl_get_line(), pressing the  escape  key  before  a  key  is
     equivalent to pressing the meta key at the same time as that
     key. Thus the key sequence M-p can be typed in two ways,  by
     pressing  the  escape  key,  followed  by  pressing p, or by
     pressing the Meta key at the same time as p.

     Under UNIX the terminal driver sets a number of special keys
     for certain functions. The tecla library attempts to use the
     same keybindings to maintain consistency. The key  sequences
     shown for the following 6 bindings are thus just examples of
     what they will probably be set to. If you have used the stty
     command  to  change  these  keys,  then the default bindings
     should match.

       ^C     -&gt;   user-interrupt
       ^\     -&gt;   abort
       ^Z     -&gt;   suspend
       ^Q     -&gt;   start-output
       ^S     -&gt;   stop-output
       ^V     -&gt;   literal-next

     The cursor keys are refered to by name, as follows. This  is
     necessary because different types of terminals generate dif-
     ferent key sequences when their cursor keys are pressed.

       right  -&gt;   cursor-right
       left   -&gt;   cursor-left
       up     -&gt;   up-history
       down   -&gt;   down-history

     The remaining bindings don't depend on  the  terminal  sett-
     tings.

       ^F     -&gt;   cursor-right
       ^B     -&gt;   cursor-left
       M-i    -&gt;   insert-mode
       ^A     -&gt;   beginning-of-line
       ^E     -&gt;   end-of-line
       ^U     -&gt;   delete-line
       ^K     -&gt;   kill-line
       M-f    -&gt;   forward-word
       M-b    -&gt;   backward-word
       ^D     -&gt;   del-char-or-list-or-eof
       ^H     -&gt;   backward-delete-char
       ^?     -&gt;   backward-delete-char
       M-d    -&gt;   forward-delete-word
       M-^H   -&gt;   backward-delete-word
       M-^?   -&gt;   backward-delete-word
       M-u    -&gt;   upcase-word
       M-l    -&gt;   downcase-word
       M-c    -&gt;   capitalize-word
       ^R     -&gt;   redisplay
       ^L     -&gt;   clear-screen
       ^T     -&gt;   transpose-chars
       ^@     -&gt;   set-mark
       ^X^X   -&gt;   exchange-point-and-mark
       ^W     -&gt;   kill-region
       M-w    -&gt;   copy-region-as-kill
       ^Y     -&gt;   yank
       ^P     -&gt;   up-history
       ^N     -&gt;   down-history
       M-p    -&gt;   history-search-backward
       M-n    -&gt;   history-search-forward
       ^I     -&gt;   complete-word
       ^X*    -&gt;   expand-filename
       ^X^F   -&gt;   read-from-file
       ^X^R   -&gt;   read-init-files
       ^Xg    -&gt;   list-glob
       ^Xh    -&gt;   list-history
       M-&lt;    -&gt;   beginning-of-history
       M-&gt;    -&gt;   end-of-history
       \n     -&gt;   newline
       \r     -&gt;   newline
       M-o    -&gt;   repeat-history
       M-^V   -&gt;   vi-mode

       M-0, M-1, ... M-9  -&gt;  digit-argument  (see below)

     Note that ^I is what the TAB key generates, and that ^@  can
     be  generated not only by pressing the control key and the @
     key simultaneously, but also by pressing the control key and
     the space bar at the same time.


</pre><h2>DEFAULT KEY BINDINGS IN VI MODE</h2><pre>
     The following default key bindings are designed to mimic the
     vi  style of editing as closely as possible. This means that
     very few editing functions are provided in the initial char-
     acter  input  mode, editing functions instead being provided
     by the vi command mode. Vi command mode is entered  whenever
     the  escape character is pressed, or whenever a key-sequence
     that starts with a meta character is entered. In addition to
     mimicing  vi, libtecla provides bindings for tab completion,
     wild-card expansion  of  file  names,  and  historical  line
     recall.

     To learn how to tell  the  tecla  library  to  use  vi  mode
     instead  of  the default emacs editing mode, see the section
     entitled THE TECLA CONFIGURATION FILE.

     As already mentioned above in the emacs section, Note that a
     key  sequence like ^A or C-a means hold the control-key down
     while pressing the letter A, and that where you see \E or M-
     in  a  binding,  this  represents the escape key or the Meta
     modifier key. Also note that to gl_get_line(), pressing  the
     escape  key  before a key is equivalent to pressing the meta
     key at the same time as that key. Thus the key sequence  M-p
     can  be  typed in two ways, by pressing the escape key, fol-
     lowed by pressing p, or by pressing the Meta key at the same
     time as p.

     Under UNIX the terminal driver sets a number of special keys
     for certain functions. The tecla library attempts to use the
     same keybindings to maintain consistency, binding them  both
     in  input  mode and in command mode. The key sequences shown
     for the following 6 bindings are thus just examples of  what
     they will probably be set to. If you have used the stty com-
     mand to change these keys, then the default bindings  should
     match.

       ^C     -&gt;   user-interrupt
       ^\     -&gt;   abort
       ^Z     -&gt;   suspend
       ^Q     -&gt;   start-output
       ^S     -&gt;   stop-output
       ^V     -&gt;   literal-next
       M-^C   -&gt;   user-interrupt
       M-^\   -&gt;   abort
       M-^Z   -&gt;   suspend
       M-^Q   -&gt;   start-output
       M-^S   -&gt;   stop-output

     Note that above, most of the  bindings  are  defined  twice,
     once as a raw control code like ^C and then a second time as
     a meta character like M-^C. The former is the binding for vi
     input mode, whereas the latter is the binding for vi command
     mode. Once in command mode all key-sequences that  the  user
     types  that  they don't explicitly start with an escape or a
     meta key, have their first key secretly converted to a  meta
     character  before  the  key sequence is looked up in the key
     binding table. Thus, once in command mode, when you type the
     letter  i,  for example, the tecla library actually looks up
     the binding for M-i.

     The cursor keys are refered to by name, as follows. This  is
     necessary because different types of terminals generate dif-
     ferent key sequences when their cursor keys are pressed.

       right  -&gt;   cursor-right
       left   -&gt;   cursor-left
       up     -&gt;   up-history
       down   -&gt;   down-history

     The cursor keys normally generate a keysequence  that  start
     with  an  escape  character,  so beware that using the arrow
     keys will put you into command mode (if you  aren't  already
     in command mode).

     The following are the terminal-independent key bindings  for
     vi input mode.

       ^D     -&gt;   list-or-eof
       ^G     -&gt;   list-glob
       ^H     -&gt;   backward-delete-char
       ^I     -&gt;   complete-word
       \r     -&gt;   newline
       \n     -&gt;   newline
       ^L     -&gt;   clear-screen
       ^N     -&gt;   down-history
       ^P     -&gt;   up-history
       ^R     -&gt;   redisplay
       ^U     -&gt;   backward-kill-line
       ^W     -&gt;   backward-delete-word
       ^X*    -&gt;   expand-filename
       ^X^F   -&gt;   read-from-file
       ^X^R   -&gt;   read-init-files
       ^?     -&gt;   backward-delete-char

     The following are the key bindings that are  defined  in  vi
     command mode, this being specified by them all starting with
     a meta character. As mentioned above, once in  command  mode
     the  initial  meta  character  is optional. For example, you
     might enter command mode by typing Esc,  and  then  press  h
     twice  to  move the cursor two positions to the left. Both h
     characters get quietly converted to M-h  before  being  com-
     pared to the key-binding table, the first one because Escape
     followed  by  a  character  is  always  converted   to   the
     equivalent  meta  character,  and the second because command
     mode was already active.

       M-\     -&gt;   cursor-right     (Meta-space)
       M-$     -&gt;   end-of-line
       M-*     -&gt;   expand-filename
       M-+     -&gt;   down-history
       M--     -&gt;   up-history
       M-&lt;     -&gt;   beginning-of-history
       M-&gt;     -&gt;   end-of-history
       M-^     -&gt;   beginning-of-line
       M-;     -&gt;   repeat-find-char
       M-,     -&gt;   invert-refind-char
       M-|     -&gt;   goto-column
       M-~     -&gt;   change-case
       M-.     -&gt;   vi-repeat-change
       M-%     -&gt;   find-parenthesis
       M-a     -&gt;   vi-append
       M-A     -&gt;   vi-append-at-eol
       M-b     -&gt;   backward-word
       M-B     -&gt;   backward-word
       M-C     -&gt;   vi-change-rest-of-line
       M-cb    -&gt;   vi-backward-change-word
       M-cB    -&gt;   vi-backward-change-word
       M-cc    -&gt;   vi-change-line
       M-ce    -&gt;   vi-forward-change-word
       M-cE    -&gt;   vi-forward-change-word
       M-cw    -&gt;   vi-forward-change-word
       M-cW    -&gt;   vi-forward-change-word
       M-cF    -&gt;   vi-backward-change-find
       M-cf    -&gt;   vi-forward-change-find
       M-cT    -&gt;   vi-backward-change-to
       M-ct    -&gt;   vi-forward-change-to
       M-c;    -&gt;   vi-change-refind
       M-c,    -&gt;   vi-change-invert-refind
       M-ch    -&gt;   vi-backward-change-char
       M-c^H   -&gt;   vi-backward-change-char
       M-c^?   -&gt;   vi-backward-change-char
       M-cl    -&gt;   vi-forward-change-char
       M-c\    -&gt;   vi-forward-change-char  (Meta-c-space)
       M-c^    -&gt;   vi-change-to-bol
       M-c0    -&gt;   vi-change-to-bol
       M-c$    -&gt;   vi-change-rest-of-line
       M-c|    -&gt;   vi-change-to-column
       M-c%    -&gt;   vi-change-to-parenthesis
       M-dh    -&gt;   backward-delete-char
       M-d^H   -&gt;   backward-delete-char
       M-d^?   -&gt;   backward-delete-char
       M-dl    -&gt;   forward-delete-char
       M-d     -&gt;   forward-delete-char    (Meta-d-space)
       M-dd    -&gt;   delete-line
       M-db    -&gt;   backward-delete-word
       M-dB    -&gt;   backward-delete-word
       M-de    -&gt;   forward-delete-word
       M-dE    -&gt;   forward-delete-word
       M-dw    -&gt;   forward-delete-word
       M-dW    -&gt;   forward-delete-word
       M-dF    -&gt;   backward-delete-find
       M-df    -&gt;   forward-delete-find
       M-dT    -&gt;   backward-delete-to
       M-dt    -&gt;   forward-delete-to
       M-d;    -&gt;   delete-refind
       M-d,    -&gt;   delete-invert-refind
       M-d^    -&gt;   backward-kill-line
       M-d0    -&gt;   backward-kill-line
       M-d$    -&gt;   kill-line
       M-D     -&gt;   kill-line
       M-d|    -&gt;   delete-to-column
       M-d%    -&gt;   delete-to-parenthesis
       M-e     -&gt;   forward-word
       M-E     -&gt;   forward-word
       M-f     -&gt;   forward-find-char
       M-F     -&gt;   backward-find-char
       M--     -&gt;   up-history
       M-h     -&gt;   cursor-left
       M-H     -&gt;   beginning-of-history
       M-i     -&gt;   vi-insert
       M-I     -&gt;   vi-insert-at-bol
       M-j     -&gt;   down-history
       M-J     -&gt;   history-search-forward
       M-k     -&gt;   up-history
       M-K     -&gt;   history-search-backward
       M-l     -&gt;   cursor-right
       M-L     -&gt;   end-of-history
       M-n     -&gt;   history-re-search-forward
       M-N     -&gt;   history-re-search-backward
       M-p     -&gt;   append-yank
       M-P     -&gt;   yank
       M-r     -&gt;   vi-replace-char
       M-R     -&gt;   vi-overwrite
       M-s     -&gt;   vi-forward-change-char
       M-S     -&gt;   vi-change-line
       M-t     -&gt;   forward-to-char
       M-T     -&gt;   backward-to-char
       M-u     -&gt;   vi-undo
       M-w     -&gt;   forward-to-word
       M-W     -&gt;   forward-to-word
       M-x     -&gt;   forward-delete-char
       M-X     -&gt;   backward-delete-char
       M-yh    -&gt;   backward-copy-char
       M-y^H   -&gt;   backward-copy-char
       M-y^?   -&gt;   backward-copy-char
       M-yl    -&gt;   forward-copy-char
       M-y\    -&gt;   forward-copy-char  (Meta-y-space)
       M-ye    -&gt;   forward-copy-word
       M-yE    -&gt;   forward-copy-word
       M-yw    -&gt;   forward-copy-word
       M-yW    -&gt;   forward-copy-word
       M-yb    -&gt;   backward-copy-word
       M-yB    -&gt;   backward-copy-word
       M-yf    -&gt;   forward-copy-find
       M-yF    -&gt;   backward-copy-find
       M-yt    -&gt;   forward-copy-to
       M-yT    -&gt;   backward-copy-to
       M-y;    -&gt;   copy-refind
       M-y,    -&gt;   copy-invert-refind
       M-y^    -&gt;   copy-to-bol
       M-y0    -&gt;   copy-to-bol
       M-y$    -&gt;   copy-rest-of-line
       M-yy    -&gt;   copy-line
       M-Y     -&gt;   copy-line
       M-y|    -&gt;   copy-to-column
       M-y%    -&gt;   copy-to-parenthesis
       M-^E    -&gt;   emacs-mode
       M-^H    -&gt;   cursor-left
       M-^?    -&gt;   cursor-left
       M-^L    -&gt;   clear-screen
       M-^N    -&gt;   down-history
       M-^P    -&gt;   up-history
       M-^R    -&gt;   redisplay
       M-^D    -&gt;   list-or-eof
       M-^I    -&gt;   complete-word
       M-\r    -&gt;   newline
       M-\n    -&gt;   newline
       M-^X^R  -&gt;   read-init-files
       M-^Xh   -&gt;   list-history

       M-0, M-1, ... M-9  -&gt;  digit-argument  (see below)

     Note that ^I is what the TAB key generates.


</pre><h2>ENTERING REPEAT COUNTS</h2><pre>
     Many of the key binding functions described previously, take
     an  optional  count, typed in before the target keysequence.
     This is interpreted as a repeat count by  most  bindings.  A
     notable  exception  is the goto-column binding, which inter-
     prets the count as a column number.

     By default you can specify this count argument  by  pressing
     the  meta key while typing in the numeric count. This relies
     on the digit-argument action being bound to  Meta-0,  Meta-1
     etc.  Once any one of these bindings has been activated, you
     can optionally take your finger off the meta key to type  in
     the rest of the number, since every numeric digit thereafter
     is treated as part of the number, unless it is  preceded  by
     the literal-next binding. As soon as a non-digit, or literal
     digit key is pressed the  repeat  count  is  terminated  and
     either  causes  the  just typed character to be added to the
     line that many times, or causes the next  key-binding  func-
     tion to be given that argument.

     For example, in emacs mode, typing:

       M-12a

     causes the letter 'a' to be added  to  the  line  12  times,
     whereas

       M-4M-c

     Capitalizes the next 4 words.

     In vi command mode the Meta modifier is automatically  added
     to  all  characters  typed  in,  so  to  enter a count in vi
     command-mode, just involves typing in the number, just as at
     it  does in the vi editor itself. So for example, in vi com-
     mand mode, typing:

       4w2x

     moves the cursor four words to the right, then  deletes  two
     characters.

     You can also bind digit-argument to other key sequences.  If
     these  end  in  a numeric digit, that digit gets appended to
     the current repeat count. If it doesn't  end  in  a  numeric
     digit,  a  new repeat count is started with a value of zero,
     and can be completed by typing in the number, after  letting
     go of the key which triggered the digit-argument action.


</pre><h2>THE TECLA CONFIGURATION FILE</h2><pre>
     By default, the first call to gl_get_line() looks for a file
     called .teclarc in your home directory (ie. ~/.teclarc).  If
     it finds this file, it reads it, interpreting each  line  as
     defining  a  new  key  binding  or  an editing configuration
     option.  Since  the  emacs  keybindings  are  installed   by
     default, if you want to use the non-default vi editing mode,
     the most important item to go in this file is the  following
     line:

       edit-mode vi

     This will re-configure the default bindings for vi-mode. The
     complete set of arguments that this command accepts are:

       vi     -  Install key-bindings like those of the vi
                 editor.
       emacs  -  Install key-bindings like those of the emacs
                 editor. This is the default.
       none   -  Use just the native line editing facilities
                 provided by the terminal driver.

     To prevent the terminal bell from being rung, such  as  when
     an unrecognized control-sequence is typed, place the follow-
     ing line in the configuration file:

       nobeep

     An example of a key binding line in the  configuration  file
     is the following.

       bind M-[2~ insert-mode

     On many keyboards, the above key sequence is generated  when
     one presses the insert key, so with this keybinding, one can
     toggle between the emacs-mode insert and overwrite modes  by
     hitting  one  key.  One  could  also do it by typing out the
     above sequence of characters one by one. As explained above,
     the M- part of this sequence can be typed either by pressing
     the escape key before the following key, or by pressing  the
     Meta  key at the same time as the following key. Thus if you
     had set the above key binding, and the insert  key  on  your
     keyboard  didn't  generate the above key sequence, you could
     still type it in either of the following 2 ways.

       1. Hit the escape key momentarily, then press '[', then '2', then
          finally '~'.

       2. Press the meta key at the same time as pressing the '[' key,
          then press '2', then '~'.

     If you set a keybinding for a key-sequence that  is  already
     bound  to a function, the new binding overrides the old one.
     If in the new binding you omit the name of the new  function
     to  bind  to  the key-sequence, the original binding becomes
     undefined.

     Starting with versions of libtecla later than  1.3.3  it  is
     now  possible  to bind keysequences that begin with a print-
     able character. Previously key-sequences  were  required  to
     start with a control or meta character.

     Note that the special  keywords  "up",  "down",  "left"  and
     "right" refer to the arrow keys, and are thus not treated as
     keysequences. So, for example, to rebind  the  up  and  down
     arrow  keys  to  use the history search mechanism instead of
     the simple history recall method, you could place  the  fol-
     lowing in your configuration file:

       bind up history-search-backwards
       bind down history-search-backwards

     To unbind an existing binding, you can do this with the bind
     command  by  omitting  to  name any action to rebind the key
     sequence to.  For example, by not specifying an action func-
     tion,  the  following command unbinds the default beginning-
     of-line action from the ^A key sequence:

       bind ^A


</pre><h2>ALTERNATE CONFIGURATION SOURCES</h2><pre>
     As mentioned above, by default users have the option of con-
     figuring  the  behavior of gl_get_line() via a configuration
     file called .teclarc in their  home  directories.  The  fact
     that  all applications share this same configuration file is
     both an advantage and a disadvantage.  In most cases  it  is
     an  advantage, since it encourages uniformity, and frees the
     user from having to configure each  application  separately.
     In  some  applications, however, this single means of confi-
     guration is a problem. This is particularly true of embedded
     software,  where  there's no filesystem to read a configura-
     tion file from, and also in applications where  a  radically
     different  choice  of  keybindings  is  needed  to emulate a
     legacy keyboard interface.  To cater  for  such  cases,  the
     following  function  allows the application to control where
     configuration information is read from.


       int gl_configure_getline(GetLine *gl,
                                const char *app_string,
                                const char *app_file,
                                const char *user_file);


     It allows the configuration commands that would normally  be
     read  from  a user's ~/.teclarc file, to be read from any or
     none of, a string,  an  application  specific  configuration
     file,  and/or  a  user-specific  configuration file. If this
     function is called before the first call  to  gl_get_line(),
     the default behavior of reading ~/.teclarc on the first call
     to gl_get_line() is disabled, so all configuration  must  be
     achieved using the configuration sources specified with this
     function.

     If app_string != NULL, then it is interpreted  as  a  string
     containing  one  or  more  configuration commands, separated
     from each other in the string by  embedded  newline  charac-
     ters. If app_file != NULL then it is interpreted as the full
     pathname of an application-specific configuration  file.  If
     user_file  !=  NULL then it is interpreted as the full path-
     name  of  a  user-specific  configuration  file,   such   as
     ~/.teclarc. For example, in the following call,

       gl_configure_getline(gl, "edit-mode vi \n nobeep",
                                "/usr/share/myapp/teclarc",
                                "~/.teclarc");

     the app_string argument causes the  calling  application  to
     start  in  vi  edit-mode, instead of the default emacs mode,
     and turns off the use of the terminal bell by  the  library.
     It  then attempts to read system-wide configuration commands
     from an optional file called /usr/share/myapp/teclarc,  then
     finally  reads  user-specific configuration commands from an
     optional .teclarc file in the user's  home  directory.  Note
     that  the  arguments are listed in ascending order of prior-
     ity, with the contents of app_string being potentially over-
     riden  by  commands  in  app_file,  and commands in app_file
     potentially being overriden by commands in user_file.
     You can call this function as  many  times  as  needed,  the
     results  being  cumulative,  but  note  that  copies  of any
     filenames specified via the app_file and user_file arguments
     are  recorded  internally  for  subsequent  use by the read-
     init-files key-binding function, so if you plan to call this
     function  multiple  times, be sure that the last call speci-
     fies the filenames that  you  want  re-read  when  the  user
     requests that the configuration files be re-read.


</pre><h2>FILENAME AND TILDE COMPLETION</h2><pre>
     With the default key bindings, pressing the  TAB  key  (aka.
     ^I)  results  in  gl_get_line()  attempting  to complete the
     incomplete filename that precedes the cursor.  gl_get_line()
     searches backwards from the cursor, looking for the start of
     the filename, stopping when it hits either a  space  or  the
     start  of  the line. If more than one file has the specified
     prefix, gl_get_line() completes the filename up to the point
     at  which  the ambiguous matches start to differ, then lists
     the possible matches.

     In addition to literally  written  filenames,  gl_get_line()
     can complete files that start with ~/ and ~user/ expressions
     and that contain $envvar expressions. In particular, if  you
     hit    TAB   within   an   incomplete   ~user,   expression,
     gl_get_line() will attempt to complete the username, listing
     any ambiguous matches.

     The   completion   binding   is   implemented   using    the
     cpl_word_completions()  function,  which  is  also available
     separately   to   users   of   this   library.    See    the
     cpl_word_completions(3) man page for more details.


</pre><h2>CUSTOMIZED WORD COMPLETION</h2><pre>
     If in your application, you would like to have  TAB  comple-
     tion  complete  other  things  in  addition to or instead of
     filenames, you can arrange this by registering an  alternate
     completion   callback   function,   via   a   call   to  the
     gl_customize_completion() function.

       int gl_customize_completion(GetLine *gl, void *data,
                                   CplMatchFn *match_fn);

     The data argument provides a way  for  your  application  to
     pass  arbitrary,  application-specific  information  to  the
     callback function. This is passed to the callback every time
     that it is called. It might for example, point to the symbol
     table from which possible completions are to be sought.  The
     match_fn  argument  specifies  the  callback  function to be
     called.  The  CplMatchFn  function  type   is   defined   in
     libtecla.h, as is a CPL_MATCH_FN() macro that you can use to
     declare and prototype callback  functions.  The  declaration
     and  responsibilities of callback functions are described in
     depth in the <a href="cpl_complete_word.html">cpl_complete_word(3)</a> man page.

     In brief, the callback function is responsible  for  looking
     backwards  in  the  input line, back from the point at which
     the user pressed TAB, to find the start of  the  word  being
     completed.  It then must lookup possible completions of this
     word, and record them  one  by  one  in  the  WordCompletion
     object  that  is passed to it as an argument, by calling the
     cpl_add_completion()  function.  If  the  callback  function
     wishes to provide filename completion in addition to its own
     specific completions, it has the option  of  itself  calling
     the  builtin  file-name  completion  callback. This also, is
     documented in the <a href="cpl_complete_word.html">cpl_complete_word(3)</a> man page.

     Note that if you would  like  gl_get_line()  to  return  the
     current  input  line  when  a  successful completion is been
     made,   you    can    arrange    this    when    you    call
     cpl_add_completion(),  by  making  the last character of the
     continuation suffix a newline character. If you do this, the
     input  line  will  be  updated  to  display  the completion,
     together with any contiuation suffix up to the newline char-
     acter, then gl_get_line() will return this input line.


</pre><h2>FILENAME EXPANSION</h2><pre>
     With  the  default  key  bindings,   pressing   ^X*   causes
     gl_get_line()  to expand the filename that precedes the cur-
     sor,  replacing  ~/  and   ~user/   expressions   with   the
     corresponding   home   directories,  and  replacing  $envvar
     expressions with the  value  of  the  specified  environment
     variable,  then if there are any wildcards, replacing the so
     far expanded filename with a  space-separated  list  of  the
     files which match the wild cards.

     The   expansion   binding   is   implemented    using    the
     ef_expand_file()  function.   See  the <a href="ef_expand_file.html">ef_expand_file(3)</a> man
     page for more details.


</pre><h2>RECALLING PREVIOUSLY TYPED LINES</h2><pre>
     Every time that a new line is entered by  the  user,  it  is
     appended  to  a  list  of  historical input lines maintained
     within the GetLine resource object. You can traverse up  and
     down  this  list  using the up and down arrow keys. Alterna-
     tively, you can do the same with the ^P, and ^N keys, and in
     vi  command mode you can alternatively use the k and j char-
     acters. Thus pressing up-arrow once,  replaces  the  current
     input  line  with  the previously entered line. Pressing up-
     arrow again, replaces this with the line  that  was  entered
     before it, etc.. Having gone back one or more lines into the
     history list, one can return  to  newer  lines  by  pressing
     down-arrow  one  or  more  times.  If you do this sufficient
     times, you will return to the original line  that  you  were
     entering when you first hit up-arrow.

     Note that in vi mode, all of the  history  recall  functions
     switch the library into command mode.

     In emacs mode the M-p and M-n keys work just like the ^P and
     ^N  keys,  except  that  they  skip all but those historical
     lines which share the prefix that precedes the cursor. In vi
     command  mode  the upper case K and J characters do the same
     thing, except that the string that they search for  includes
     the character under the cursor as well as what precedes it.

     Thus for example, suppose that you were in emacs  mode,  and
     you  had  just entered the following list of commands in the
     order shown:

       ls ~/tecla/
       cd ~/tecla
       ls -l getline.c
       emacs ~/tecla/getline.c

     If you next typed:

       ls

     and then hit M-p, then rather than returning the  previously
     typed   emacs   line,   which   doesn't   start  with  "ls",
     gl_get_line() would  recall  the  "ls  -l  getline.c"  line.
     Pressing M-p again would recall the "ls ~/tecla/" line.


</pre><h2>HISTORY FILES</h2><pre>
     To save the contents of the history buffer  before  quitting
     your  application,  and  subsequently  restore them when you
     next start the application, the following functions are pro-
     vided.


      int gl_save_history(GetLine *gl, const char *filename,
                          const char *comment, int max_lines);
      int gl_load_history(GetLine *gl, const char *filename,
                          const char *comment);


     The filename argument specifies the name to give the history
     file  when  saving, or the name of an existing history file,
     when loading. This may contain home-directory  and  environ-
     ment  variable  expressions,  such  as "~/.myapp_history" or
     "$HOME/.myapp_history".
     Along with each history line, extra  information  about  it,
     such  as when it was entered by the user, and what its nest-
     ing level is, is recorded as a comment preceding the line in
     the  history file. Writing this as a comment allows the his-
     tory file to double as a command file, just in case you wish
     to  replay  a whole session using it. Since comment prefixes
     differ in different languages, the comment argument is  pro-
     vided  for  specifying  the  comment prefix. For example, if
     your application were a  unix  shell,  such  as  the  bourne
     shell,  you  would specify "#" here. Whatever you choose for
     the comment character, you must specify the same  prefix  to
     gl_load_history()    that   you   used   when   you   called
     gl_save_history() to write the history file.

     The max_lines must be either -1 to specify that all lines in
     the history list be saved, or a positive number specifying a
     ceiling on how many of  the  most  recent  lines  should  be
     saved.

     Both fuctions return non-zero on  error,  after  writing  an
     error  message  to  stderr. Note that gl_load_history() does
     not consider the non-existence of a file to be an error.


</pre><h2>MULTIPLE HISTORY LISTS</h2><pre>
     If your application uses a single GetLine object for  enter-
     ing  many  different  types  of  input  lines,  you may wish
     gl_get_line() to distinguish the different types of lines in
     the  history  list,  and  only  recall  lines that match the
     current  type  of  line.  To   support   this   requirement,
     gl_get_line() marks lines being recorded in the history list
     with an integer identifier chosen by the application.   Ini-
     tially  this identifier is set to 0 by new_GetLine(), but it
     can be changed subsequently by calling gl_group_history().


       int gl_group_history(GetLine *gl, unsigned id);


     The integer identifier id can be any number  chosen  by  the
     application,    but    note   that   gl_save_history()   and
     gl_load_history() preserve the association between  identif-
     iers and historical input lines between program invokations,
     so you should choose fixed  identifiers  for  the  different
     types of input line used by your application.

     Whenever gl_get_line() appends a new input line to the  his-
     tory  list,  the current history identifier is recorded with
     it, and when it is asked to recall a historical input  line,
     it only recalls lines that are marked with the current iden-
     tifier.

</pre><h2>DISPLAYING HISTORY</h2><pre>
     The   history   list   can   be   displayed    by    calling
     gl_show_history().


       int gl_show_history(GetLine *gl, FILE *fp,
                           const char *fmt,
                           int all_groups,
                           int max_lines);


     This displays the current contents of the  history  list  to
     the  stdio  output  stream  fp. If the max_lines argument is
     greater than or equal to zero, then no more than this number
     of   the  most  recent  lines  will  be  displayed.  If  the
     all_groups argument is  non-zero,  lines  from  all  history
     groups  are displayed. Otherwise just those of the currently
     selected history group  are  displayed.  The  format  string
     argument,  fmt,  determines  how the line is displayed. This
     can contain arbitrary characters which are written verbatim,
     interleaved with any of the following format directives:

       %D  -  The date on which the line was originally
              entered, formatted like 2001-11-20.
       %T  -  The time of day when the line was entered,
              formatted like 23:59:59.
       %N  -  The sequential entry number of the line in
              the history buffer.
       %G  -  The number of the history group which the
              line belongs to.
       %%  -  A literal % character.
       %H  -  The history line itself.

     Thus a format string like "%D %T  %H0 would output something
     like:

       2001-11-20 10:23:34  Hello world

     Note the inclusion of an explicit newline character  in  the
     format string.


</pre><h2>LOOKING UP HISTORY</h2><pre>
     The gl_lookup_history() function allows the calling applica-
     tion to look up lines in the history list.


       typedef struct {
         const char *line;    /* The requested historical */
                              /*  line. */
         unsigned group;      /* The history group to which */
                              /*  the line belongs. */
         time_t timestamp;    /* The date and time at which */
                              /*  the line was originally */
                              /*  entered. */
       } GlHistoryLine;

       int gl_lookup_history(GetLine *gl, unsigned long id,
                             GlHistoryLine *hline);


     The id argument indicates which line to look up,  where  the
     first  line  that  was  entered  in  the  history list after
     new_GetLine() was called, is denoted by 0, and  subsequently
     entered  lines are denoted with successively higher numbers.
     Note that the range of lines currently preserved in the his-
     tory    list    can    be    queried    by    calling    the
     gl_range_of_history()  function,  described  later.  If  the
     requested  line  is  in the history list, the details of the
     line are recorded in the variable pointed to  by  the  hline
     argument,  and  1  is returned. Otherwise 0 is returned, and
     the variable pointed to by hline is left unchanged.

     Beware that the string returned in hline-&gt;line  is  part  of
     the  history  buffer,  so  it  must  not  be modified by the
     caller, and will be recycled on the next call to  any  func-
     tion  that  takes  gl  as its argument. Therefore you should
     make a private copy of this string if you need  to  keep  it
     around.


</pre><h2>MISCELLANEOUS HISTORY CONFIGURATION</h2><pre>
     If you wish to change the size of the  history  buffer  that
     was  originally  specified in the call to new_GetLine(), you
     can do so with the gl_resize_history() function.


       int gl_resize_history(GetLine *gl, size_t histlen);


     The histlen argument specifies the new size in bytes, and if
     you specify this as 0, the buffer will be deleted.

     As mentioned in the discussion of new_GetLine(), the  number
     of  lines  that can be stored in the history buffer, depends
     on the lengths of the individual lines. For example, a  1000
     byte  buffer  could equally store 10 lines of average length
     100 bytes, or 2 lines of average length 50  bytes.  Although
     the  buffer  is  never  expanded when new lines are added, a
     list of pointers into the  buffer  does  get  expanded  when
     needed to accomodate the number of lines currently stored in
     the buffer. To place an upper limit on the number  of  lines
     in  the  buffer,  and thus a ceiling on the amount of memory
     used in this  list,  you  can  call  the  gl_limit_history()
     function.


       void gl_limit_history(GetLine *gl, int max_lines);


     The max_lines should either  be  a  positive  number  &gt;=  0,
     specifying  an  upper  limit  on  the number of lines in the
     buffer, or be -1 to cancel any previously  specified  limit.
     When  a limit is in effect, only the max_lines most recently
     appended lines are kept in the buffer. Older lines are  dis-
     carded.

     To  discard  lines  from  the  history   buffer,   use   the
     gl_clear_history() function.

       void gl_clear_history(GetLine *gl, int all_groups);

     The all_groups argument tells the function whether to delete
     just  the  lines  associated  with the current history group
     (see gl_group_history()), or all  historical  lines  in  the
     buffer.

     The gl_toggle_history() function allows you to  toggle  his-
     tory  on  and off without losing the current contents of the
     history list.


       void gl_toggle_history(GetLine *gl, int enable);


     Setting the enable argument  to  0  turns  off  the  history
     mechanism,  and  setting it to 1 turns it back on. When his-
     tory is turned off, no new lines will be added to  the  his-
     tory  list,  and  history  lookup  key-bindings  will act as
     though there is nothing in the history buffer.


</pre><h2>QUERYING HISTORY INFORMATION</h2><pre>
     The configured state of the history list can be queried with
     the gl_history_state() function.


       typedef struct {
         int enabled;     /* True if history is enabled */
         unsigned group;  /* The current history group */
         int max_lines;   /* The current upper limit on the */
                          /*  number of lines in the history */
                          /*  list, or -1 if unlimited. */
       } GlHistoryState;

       void gl_state_of_history(GetLine *gl,
                                GlHistoryState *state);

     On return, the status information is recorded in  the  vari-
     able pointed to by the state argument.

     The gl_range_of_history() function returns  the  number  and
     range of lines in the history list.


     typedef struct {
       unsigned long oldest;  /* The sequential entry number */
                              /*  of the oldest line in the */
                              /*  history list. */
       unsigned long newest;  /* The sequential entry number */
                              /*  of the newest line in the */
                              /*  history list. */
       int nlines;            /* The number of lines in the */
                              /*  history list. */
     } GlHistoryRange;

     void gl_range_of_history(GetLine *gl, GlHistoryRange *range);

     The return values are recorded in the variable pointed to by
     the  range  argument. If the nlines member of this structure
     is greater than zero, then the  oldest  and  newest  members
     report    the    range   of   lines   in   the   list,   and
     newest=oldest+nlines-1.  Otherwise they are both zero.

     The gl_size_of_history() function returns the total size  of
     the  history  buffer  and  the  amount of the buffer that is
     currently occupied.

       typedef struct {
         size_t size;      /* The size of the history buffer */
                           /*  (bytes). */
         size_t used;      /* The number of bytes of the */
                           /*  history buffer that are */
                           /*  currently occupied. */
       } GlHistorySize;

       void gl_size_of_history(GetLine *gl, GlHistorySize *size);

     On return, the size information is recorded in the  variable
     pointed to by the size argument.


</pre><h2>CHANGING TERMINALS</h2><pre>
     The new_GetLine() constructor function assumes that input is
     to  be  read  from  stdin, and output written to stdout. The
     following function allows you to switch to  different  input
     and output streams.

       int gl_change_terminal(GetLine *gl, FILE *input_fp,
                              FILE *output_fp, const char *term);

     The  gl  argument  is  the  object  that  was  returned   by
     new_GetLine().   The  input_fp argument specifies the stream
     to read from, and output_fp specifies the stream to be writ-
     ten  to.  Only  if  both  of these refer to a terminal, will
     interactive   terminal   input   be   enabled.     Otherwise
     gl_get_line()  will  simply  call  fgets()  to  read command
     input. If both streams refer to a terminal, then  they  must
     refer  to  the  same terminal, and the type of this terminal
     must be specified via the term argument. The  value  of  the
     term argument is looked up in the terminal information data-
     base (terminfo or termcap), in order to determine which spe-
     cial control sequences are needed to control various aspects
     of the  terminal.  new_GetLine()  for  example,  passes  the
     return  value  of getenv("TERM") in this argument. Note that
     if one or both of input_fp and output_fp don't  refer  to  a
     terminal,  then it is legal to pass NULL instead of a termi-
     nal type.

     Note  that  if  you  want  to  pass  file   descriptors   to
     gl_change_terminal(),  you  can  do  this  by creating stdio
     stream wrappers using the POSIX fdopen() function.


</pre><h2>EXTERNAL EVENT HANDLING</h2><pre>
     While gl_get_line() is waiting for keyboard input  from  the
     user, you can ask it to also watch for activity on arbitrary
     file descriptors, such as network sockets,  pipes  etc,  and
     have  it  call  functions  of your choosing when activity is
     seen. This works on any system that has the select()  system
     call, which is most, if not all flavors of unix. Registering
     a file descriptor to be watched  by  gl_get_line()  involves
     calling the gl_watch_fd() function.


       int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
                       GlFdEventFn *callback, void *data);


     If this returns non-zero, then it  means  that  either  your
     arguments are invalid, or that this facility isn't supported
     on the host system.

     The fd argument is the file descriptor to  be  watched.  The
     event  argument  specifies  what  type  of  activity  is  of
     interest, chosen from the following enumerated values:


       GLFD_READ   -  Watch for the arrival of data to be read.
       GLFD_WRITE  -  Watch for the ability to write to the file
                      descriptor without blocking.
       GLFD_URGENT -  Watch for the arrival of urgent
                      out-of-band data on the file descriptor.


     The callback argument is  the  function  to  call  when  the
     selected  activity  is  seen.  It should be defined with the
     following macro, which is defined in libtecla.h.


       #define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, \
                                           void *data, int fd, \
                                           GlFdEvent event)

     The data argument of the gl_watch_fd() function is passed to
     the callback function for its own use, and can point to any-
     thing you like, including NULL. The file descriptor and  the
     event argument are also passed to the callback function, and
     this potentially allows the same  callback  function  to  be
     registered  to  more than one type of event and/or more than
     one file descriptor. The return value of the callback  func-
     tion should be one of the following values.


       GLFD_ABORT    -  Tell gl_get_line() to abort with an
                        error (errno won't be set, so set it
                        appropriately yourself if you need it).
       GLFD_REFRESH  -  Redraw the input line then continue
                        waiting for input. Return this if
                        your callback wrote to the terminal.
       GLFD_CONTINUE -  Continue to wait for input, without
                        redrawing the line.

     Note that before calling the callback, gl_get_line()  blocks
     most  signals, and leaves its own signal handlers installed,
     so if you need to catch a particular signal you will need to
     both  temporarily  install  your  own  signal  handler,  and
     unblock the signal. Be sure to re-block the  signal  (if  it
     was  originally  blocked)  and reinstate the original signal
     handler, if any, before returning.

     Your callback shouldn't try to read from the terminal, which
     is  left  in  raw mode as far as input is concerned. You can
     however write to the terminal as usual, since features  like
     conversion  of  newline  to carriage-return/linefeed are re-
     enabled while the callback  is  running.  If  your  callback
     function  does  write  to  the terminal, be sure to output a
     newline  first,  and  when  your  callback   returns,   tell
     gl_get_line()  that  the  input line needs to be redrawn, by
     returning the GLFD_REFRESH status code.

     To remove a callback function that you previously registered
     for   a   given  file  descriptor  and  event,  simply  call
     gl_watch_fd() with the same file descriptor and event  argu-
     ments,  but with a callback argument of 0. The data argument
     is ignored in this case.


</pre><h2>SIGNAL HANDLING DEFAULTS</h2><pre>
     By default, the gl_get_line() function intercepts  a  number
     of signals. This is particularly important for signals which
     would by default terminate the process, since  the  terminal
     needs  to be restored to a usable state before this happens.
     In this section, the signals that are  trapped  by  default,
     and how gl_get_line() responds to them, is described. Chang-
     ing these defaults is the topic of the following section.

     When  the  following   subset   of   signals   are   caught,
     gl_get_line()  first restores the terminal settings and sig-
     nal handling to  how  they  were  before  gl_get_line()  was
     called,   resends   the   signal,   to   allow  the  calling
     application's signal handlers to handle it, then if the pro-
     cess still exists, gl_get_line() returns NULL and sets errno
     as specified below.


      SIGINT  -  This signal is generated both by the keyboard
                 interrupt key (usually ^C), and the keyboard
                 break key.

                 errno=EINTR

      SIGHUP  -  This signal is generated when the controlling
                 terminal exits.

                 errno=ENOTTY

      SIGPIPE -  This signal is generated when a program attempts
                 to write to a pipe who's remote end isn't being
                 read by any process. This can happen for example
                 if you have called gl_change_terminal() to
                 redirect output to a pipe hidden under a pseudo
                 terminal.

                 errno=EPIPE

      SIGQUIT -  This signal is generated by the keyboard quit
                 key (usually ^\).

                 errno=EINTR

      SIGABRT -  This signal is generated by the standard C,
                 abort() function. By default it both
                 terminates the process and generates a core
                 dump.

                 errno=EINTR

      SIGTERM -  This is the default signal that the UN*X
                 kill command sends to processes.

                 errno=EINTR

     Note that in the case of all of  the  above  signals,  POSIX
     mandates that by default the process is terminated, with the
     addition of a core dump in the case of the  SIGQUIT  signal.
     In  other words, if the calling application doesn't override
     the default handler by supplying  its  own  signal  handler,
     receipt  of  the  corresponding  signal  will  terminate the
     application before gl_get_line() returns.

     If gl_get_line() aborts with errno set  to  EINTR,  you  can
     find out what signal caused it to abort, by calling the fol-
     lowing function.

       int gl_last_signal(const GetLine *gl);

     This returns the numeric code (eg. SIGINT) of the last  sig-
     nal  that  was  received  during  the  most  recent  call to
     gl_get_line(), or -1 if no signals were received.

     On systems that support it, when a SIGWINCH (window  change)
     signal  is  received,  gl_get_line() queries the terminal to
     find out its new size, redraws the  current  input  line  to
     accomodate  the  new  size, then returns to waiting for key-
     board input from the user. Unlike other signals, this signal
     isn't resent to the application.

     Finally, the following signals cause gl_get_line() to  first
     restore  the  terminal  and signal environment to that which
     prevailed before gl_get_line() was called, then  resend  the
     signal to the application. If the process still exists after
     the signal has been delivered, then gl_get_line()  then  re-
     establishes  its  own signal handlers, switches the terminal
     back to raw mode, redisplays the input line, and  goes  back
     to awaiting terminal input from the user.

      SIGCONT    -  This signal is generated when a suspended
                    process is resumed.

      SIGPWR     -  This signal is generated when a power failure
                    occurs (presumably when the system is on a
                    UPS).

      SIGALRM    -  This signal is generated when a timer
                    expires.
      SIGUSR1    -  An application specific signal.

      SIGUSR2    -  Another application specific signal.

      SIGVTALRM  -  This signal is generated when a virtual
                    timer expires (see man setitimer(2)).

      SIGXCPU    -  This signal is generated when a process
                    exceeds its soft CPU time limit.

      SIGTSTP    -  This signal is generated by the terminal
                    suspend key, which is usually ^Z, or the
                    delayed terminal suspend key, which is
                    usually ^Y.

      SIGTTIN    -  This signal is generated if the program
                    attempts to read from the terminal while the
                    program is running in the background.

      SIGTTOU    -  This signal is generated if the program
                    attempts to write to the terminal while the
                    program is running in the background.


     Obviously not all of the above signals are supported on  all
     systems,  so  code to support them is conditionally compiled
     into the tecla library.

     Note that if SIGKILL, which by definition can't  be  caught,
     or  any of the hardware generated exception signals, such as
     SIGSEGV, SIGBUS and SIGFPE, are received and unhandled while
     gl_get_line() has the terminal in raw mode, the program will
     be terminated without the terminal having been restored to a
     usable  state. In practice, job-control shells usually reset
     the terminal settings when a process relinquishes  the  con-
     trolling  terminal,  so  this  is  only a problem with older
     shells.


</pre><h2>CUSTOMIZED SIGNAL HANDLING</h2><pre>
     The previous section listed the signals  that  gl_get_line()
     traps  by  default,  and  described how it responds to them.
     This section describes how to both add  and  remove  signals
     from  the  list  of  trapped signals, and how to specify how
     gl_get_line() should respond to a given signal.

     If you don't need gl_get_line() to do anything  in  response
     to  a  signal  that  it  normally  traps,  you  can  tell to
     gl_get_line()   to   ignore   that   signal    by    calling
     gl_ignore_signal().

       int gl_ignore_signal(GetLine *gl, int signo);
     The signo argument is the number of the signal (eg.  SIGINT)
     that you want to have ignored. If the specified signal isn't
     currently one of those being  trapped,  this  function  does
     nothing.

     The gl_trap_signal() function allows you to either add a new
     signal  to  the list that gl_get_line() traps, or modify how
     it responds to a signal that it already traps.

       int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
                          GlAfterSignal after, int errno_value);

     The signo argument is the number of the signal that you wish
     to  have trapped. The flags argument is a set of flags which
     determine the environment in which the application's  signal
     handler  is  invoked, the after argument tells gl_get_line()
     what to do after the application's signal  handler  returns,
     and  errno_value tells gl_get_line() what to set errno to if
     told to abort.

     The flags argument is a bitwise OR of zero or  more  of  the
     following enumerators:

       GLS_RESTORE_SIG  -  Restore the caller's signal
                           environment while handling the
                           signal.

       GLS_RESTORE_TTY  -  Restore the caller's terminal settings
                           while handling the signal.

       GLS_RESTORE_LINE -  Move the cursor to the start of the
                           line following the input line before
                           invoking the application's signal
                           handler.

       GLS_REDRAW_LINE  -  Redraw the input line when the
                           application's signal handler returns.

       GLS_UNBLOCK_SIG  -  Normally, if the calling program has
                           a signal blocked (man sigprocmask),
                           gl_get_line() does not trap that
                           signal. This flag tells gl_get_line()
                           to trap the signal and unblock it for
                           the duration of the call to
                           gl_get_line().

       GLS_DONT_FORWARD -  If this flag is included, the signal
                           will not be forwarded to the signal
                           handler of the calling program.

     Two commonly useful flag combinations are also enumerated as
     follows:
       GLS_RESTORE_ENV   = GLS_RESTORE_SIG | GLS_RESTORE_TTY |
                           GLS_REDRAW_LINE

       GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE


     If your signal handler, or the default system signal handler
     for  this  signal, if you haven't overriden it, never either
     writes to the terminal, nor suspends or terminates the  cal-
     ling  program, then you can safely set the flags argument to
     0.

     If your signal handler always writes to the terminal,  reads
     from  it,  or suspends or terminates the program, you should
     specify the flags argument as GL_SUSPEND_INPUT, so that:

     1. The cursor doesn't get left in the middle of the input
        line.
     2. So that the user can type in input and have it echoed.
     3. So that you don't need to end each output line with
        \r\n, instead of just \n.

     The   GL_RESTORE_ENV   combination   is    the    same    as
     GL_SUSPEND_INPUT,  except  that  it doesn't move the cursor,
     and if your signal handler doesn't read or write anything to
     the terminal, the user won't see any visible indication that
     a signal was caught. This can be useful if you have a signal
     handler that only occasionally writes to the terminal, where
     using GL_SUSPEND_LINE would  cause  the  input  line  to  be
     unnecessarily  duplicated  when  nothing had been written to
     the terminal.  Such a signal handler, when it does write  to
     the  terminal,  should  be  sure  to start a new line at the
     start of its first write,  by  writing  a  new  line  before
     returning.  If the signal arrives while the user is entering
     a line that only occupies a signal terminal line, or if  the
     cursor  is on the last terminal line of a longer input line,
     this will have the same effect as  GL_SUSPEND_INPUT.  Other-
     wise  it  will start writing on a line that already contains
     part of the displayed input line.  This doesn't do any harm,
     but  it  looks a bit ugly, which is why the GL_SUSPEND_INPUT
     combination is better if you know that you are always  going
     to be writting to the terminal.

     The after argument, which determines what gl_get_line() does
     after  the  application's  signal  handler  returns  (if  it
     returns), can take any one of the following values:

       GLS_RETURN   - Return the completed input line, just as
                      though the user had pressed the return
                      key.

       GLS_ABORT    - Cause gl_get_line() to return NULL.
       GLS_CONTINUE - Resume command line editing.

     The errno_value argument is intended to be combined with the
     GLS_ABORT  option,  telling  gl_get_line()  what  to set the
     standard errno variable to before returning NULL to the cal-
     ling  program.  It  can  also,  however,  be  used  with the
     GL_RETURN option, in case you wish to have a way to  distin-
     guish  between  an  input  line  that  was entered using the
     return key, and one that was entered by  the  receipt  of  a
     signal.


</pre><h2>THE TERMINAL SIZE</h2><pre>
     On most systems the combination of the TIOCGWINSZ ioctl  and
     the  SIGWINCH signal is used to maintain an accurate idea of
     the terminal size. The terminal size is newly queried  every
     time  that  gl_get_line()  is called and whenever a SIGWINCH
     signal is received.

     On the few systems where this mechanism isn't available,  at
     startup  new_GetLine() first looks for the LINES and COLUMNS
     environment variables.  If these aren't found, or they  con-
     tain  unusable  values, then if a terminal information data-
     base like terminfo or termcap is available, the default size
     of  the  terminal is looked up in this database. If this too
     fails to provide the terminal size, a  default  size  of  80
     columns by 24 lines is used. If this default isn't appropri-
     ate for your system, gl_terminal_size() can be used to  sup-
     ply a different fallback.

     The gl_terminal_size() function  allows  you  to  query  the
     current size of the terminal, and install an alternate fall-
     back size for cases where the size isn't available.   Beware
     that  the terminal size won't be available if reading from a
     pipe or a file, so the default values can be important  even
     on  systems that do support ways of finding out the terminal
     size.

       typedef struct {
         int nline;        /* The terminal has nline lines */
         int ncolumn;      /* The terminal has ncolumn columns */
       } GlTerminalSize;

       GlTerminalSize gl_terminal_size(GetLine *gl,
                                       int def_ncolumn,
                                       int def_nline);

     This function first updates gl_get_line()'s idea of the ter-
     minal size, then records its findings in the return value.

     The def_ncolumn and def_nline specify the default number  of
     terminal columns and lines to use if the terminal size can't
     be determined.


</pre><h2>HIDING WHAT YOU TYPE</h2><pre>
     When entering sensitive information, such as  passwords,  it
     is best not to have the text that you are entering echoed on
     the terminal.  Furthermore, such text should not be recorded
     in  the  history  list, since somebody finding your terminal
     unattended  could  then  recall  it,  or  somebody  snooping
     through  your directories could see it in your history file.
     With this in mind, the gl_echo_mode() function allows you to
     toggle  on and off the display and archival of any text that
     is subsequently entered in calls to gl_get_line().


       int gl_echo_mode(GetLine *gl, int enable);


     The enable argument specifies whether entered text should be
     visible  or not. If it is 0, then subsequently entered lines
     will not be  visible  on  the  terminal,  and  will  not  be
     recorded  in  the  history list. If it is 1, then subsequent
     input lines will be displayed as they are entered, and  pro-
     vided  that  history  hasn't  been  turned off via a call to
     gl_toggle_history(), then they will also be archived in  the
     history  list.  Finally,  if the enable argument is -1, then
     the echoing mode is left  unchanged,  which  allows  you  to
     non-destructively  query  the current setting via the return
     value. In all cases, the return value of the function  is  0
     if  echoing was disabled before the function was called, and
     1 if it was enabled.

     When echoing is turned off, note that although  tab  comple-
     tion will invisibly complete your prefix as far as possible,
     ambiguous completions will not be displayed.


</pre><h2>CALLBACK FUNCTION FACILITIES</h2><pre>
     Unless otherwise stated, callback  functions,  such  as  tab
     completion callbacks and event callbacks should not call any
     functions in this module. The following functions,  however,
     are designed specifically to be used by callback functions.

     Calling the gl_replace_prompt()  function  from  a  callback
     tells  gl_get_line()  to display a different prompt when the
     callback  returns.  It  has  no  effect   if   called   when
     gl_get_line() is not being called.

       void gl_replace_prompt(GetLine *gl, const char *prompt);



</pre><h2>INTERNATIONAL CHARACTER SETS</h2><pre>
     Since libtecla version 1.4.0, gl_get_line() has  been  8-bit
     clean.  This means that all 8-bit characters that are print-
     able in the user's current locale are now displayed verbatim
     and  included in the returned input line.  Assuming that the
     calling program correctly contains a call like  the  follow-
     ing,

       setlocale(LC_CTYPE, "");

     then the current locale is determined by the  first  of  the
     environment  variables  LC_CTYPE,  LC_ALL, and LANG, that is
     found to contain a valid locale name. If none of these vari-
     ables  are  defined,  or the program neglects to call setlo-
     cale, then the default C locale is used, which is  US  7-bit
     ASCII.  On  most  unix-like platforms, you can get a list of
     valid locales by typing the command:

       locale -a

     at the shell prompt.


</pre><h2>  Meta keys and locales</h2><pre>
     Beware that in most locales other than the default C locale,
     meta  characters  become  printable,  and  they  are then no
     longer considered to match  M-c  style  key  bindings.  This
     allows  international characters to be entered with the com-
     pose key without unexpectedly triggering meta key  bindings.
     You can still invoke meta bindings, since there are actually
     two ways to do this. For example the binding M-c can also be
     invoked  by pressing the escape key momentarily, then press-
     ing the c key, and this  will  work  regardless  of  locale.
     Moreover,  many  modern  terminal emulators, such as gnome's
     gnome-terminal's and KDE's konsole terminals,  already  gen-
     erate  escape  pairs  like  this  when you use the meta key,
     rather than a real meta character, and other emulators  usu-
     ally  have  a  way to request this behavior, so you can con-
     tinue to use the meta key on most systems.

     For example, although xterm terminal emulators generate real
     8-bit  meta characters by default when you use the meta key,
     they can be configured to output the equivalent escape  pair
     by  setting their EightBitInput X resource to False. You can
     either do this by placing a line like the following in  your
     ~/.Xdefaults file,

       XTerm*EightBitInput: False

     or by starting an xterm with an -xrm '*EightBitInput: False'
     command-line  argument.  In recent versions of xterm you can
     toggle this feature on and off with the "Meta Sends  Escape"
     option in the menu that is displayed when you press the left
     mouse button and the control key within an xterm window.  In
     CDE,  dtterms  can  be  similarly coerced to generate escape
     pairs  in  place  of  meta  characters,   by   setting   the
     Dtterm*KshMode resource to True.


</pre><h2>  Entering international characters</h2><pre>
     If you don't have a  keyboard  that  generates  all  of  the
     international  characters  that you need, there is usually a
     compose key that will allow you to enter special characters,
     or  a  way  to  create  one. For example, under X windows on
     unix-like systems, if your keyboard doesn't have  a  compose
     key, you can designate a redundant key to serve this purpose
     with the xmodmap command. For example, on many PC  keyboards
     there is a microsoft-windows key, which is otherwise useless
     under Linux. On my PC the xev program reports that  pressing
     this  key  generates keycode 115, so to turn this key into a
     compose key, I do the following:

       xmodmap -e 'keycode 115 = Multi_key'

     I can then enter an i with a umlaut over it by  typing  this
     key, followed by ", followed by i.


</pre><h2>THREAD SAFETY</h2><pre>
     In a multi-threaded program, you should use the libtecla_r.a
     version of the library. This uses reentrant versions of sys-
     tem functions, where available. Unfortunately  neither  ter-
     minfo  nor  termcap  were  designed  to be reentrant, so you
     can't safely use the functions of the getline module in mul-
     tiple  threads  (you can use the separate file-expansion and
     word-completion  modules  in  multiple  threads,   see   the
     corresponding man pages for details). However due to the use
     of POSIX reentrant functions for looking up home directories
     etc, it is safe to use this module from a single thread of a
     multi-threaded program, provided  that  your  other  threads
     don't use any termcap or terminfo functions.


</pre><h2>FILES</h2><pre>
     libtecla.a      -    The tecla library
     libtecla.h      -    The tecla header file.
     ~/.teclarc      -    The personal tecla customization file.


</pre><h2>SEE ALSO</h2><pre>
     <a href="libtecla.html">libtecla(3)</a>,    <a href="ef_expand_file.html">ef_expand_file(3)</a>,     <a href="cpl_complete_word.html">cpl_complete_word(3)</a>,
     <a href="pca_lookup_file.html">pca_lookup_file(3)</a>


</pre><h2>AUTHOR</h2><pre>
     Martin Shepherd  (mcs@astro.caltech.edu)


















































</pre>
</body>
